Network Supervisor's Toolkit/Network Supervisor's Toolkit.iso/logins/jb-learn/jb-learn.doc

Text File | 1996-07-10 | 23KB | 512 lines

                                 JB-LEARN
                               Version 1.2
                         for {COMMO} Version 6.4X
                      Copyright (C) 1995, Jeff Bishop
                             February 4, 1995

Introduction

     I have always loved writing {COMMO} macros.  After examining other
     telecommunication programs to see what could be added to {COMMO} I came
     up with the idea of writing a automatic learn macro for {COMMO}.

     The {COMMO} macro language is very complex.  Many users have
     been scared of it due to this fact.  I thought to myself
     "what could I do to make it easier".  I decided to write a
     macro that would create {COMMO} macros for login activities
     (or any activity the user wishes).  After weeks of work, JB
     Learn was born to satisfy this requirement/need.

What Can JB-Learn do?

     JB-Learn has the following features:

     -    A very solid learn engine to create ready-to-run macros
          after learn mode is complete.

     -    A learn data file capacity to make future learning more
          intelligent.  The learn macro learns as you use it.  This
          is a first in the BBS community.  Find another learn
          engine that can do that (except CS-LEARN for {COMMO}).
          The user has complete control as to what it learns.

     -    The learn data file will process {COMMO} variables for
          you.  This gives you even more power.  This allows for great
          flexibility when using CS-MAC since it defines a wealth of
          variables that you can use.

     -    Have complete control of your learning experience.  You
          make the decisions if you want to.  This provides the
          ability to correct mistakes that the learn can not
          handle.  This provides the ability to create very solid
          macros.  Just think, you tell the teacher what to do and get a
          better grade for it.

     -    Automatic detection of front end mailers.  No need to
          press <ESCAPE> twice any more (even during learning) as long as
          EMSI protocol is being used.

     -    The learn can automatically try to log you in without
          user intervention.  This is similar to most other
          conventional learn engines available in other
          communication programs.

     -    The ability to add SSLOOK logic in your macros. This will make them
          more stream lined for those nagging prompts often seen on BBS's.
          Also added logic to allow for forwarding SSLOOKS  after each
          LOOKFOR/SEND combination.  Define the SSLOOK once and use it over
          and over again if need be.

     -    The macro is FREE for your use.  The source code is very
          well commented for a great learning experience.

Installing JB-LEARN

     Installing JB-Learn is very easy.  Follow these steps:

     1.   Copy the file JB-LEARN.MAC to the {COMMO} home directory (the
          directory that you installed {COMMO} in).  If you do not plan on
          modifying the source of JB-Learn you might consider using the
          already compiled version of it.  This will load quicker into
          {COMMO}.  If you want to do this simply copy JB-LEARN.CCM to
          JB-LEARN.MAC in your {COMMO} home directory.  The compiled
          version is much smaller than the source version.

     2.   The file MY_COMMO.MAC is a slightly modified version of the
          {COMMO} 6.41 COMMO.MAC file.  This macro file has a label that
          points to JB-LEARN.MAC.  In addition, it has been added to the
          ALT-U utility menu.  Besides that, it is a standard COMMO.MAC
          file.  If you have not modified your COMMO.MAC file extensively
          then simply copy this file over your existing COMMO.MAC.
          Otherwise, continue to step 3.

     3.   Add the following line to the end of your COMMO.MAC
          file that is located in your {COMMO} home directory:

          {:LEARN} {GOTO JB-LEARN,JB-LEARN.MAC} {STOP}

          This line will make it a lot easier to add macro links to your
          dialing directory.

Adding the Macro Links

     This section describes how to add macro links to your
     dialing directory.  If you are using JB-Learn within CS-MAC,
     this is not necessary.  CS-MAC accommodates JB-Learn by using
     the standard login macro links used for mail runs on others.
     These are GLR (generic login) and QWK (mail run).  The way
     that CS-MAC knows that you are wanting to perform a learn is
     by you selecting the learn from the CS-MAC menu structure.
     The learn macro can be setup by selecting ALT-M (macro
     menu), O (online menu, which will be automatically selected
     if you are online), R (Learn).  That is all you have to do.

     If you have downloaded JB-Learn as a stand alone package
     then you will need to add macro links to your dialing
     directory.  Here is an example of what this would look like:

     Demodulator {290 2807} {PASSWORD} {LEARN} {} 00/00/00

     The third set of braces ({}) is where the macro link is
     placed.  Your macro link should look exactly like that one
     (assuming you added the line to commo.mac in the previous
     section).  Your dialing directory may have other settings (or
     even a linked macro already).  Simply substitute the linked
     macro you may have installed for the BBS with this one.  All
     other parameters will be used during your login (terminal
     settings, password, etc.).

Before Running JB-Learn

     Before you run JB-Learn you should have a very solid
     understanding of what it takes to login to your system.  The
     key thing you must determine is if the BBS uses hot keys or
     whether all responses require that the <ENTER> key be
     pressed.  Try logging into your BBS a few times to insure you
     understand what responses are required.  This will be very
     important when you make decisions about the login.

Special Variables Defined in JB-Learn

     JB-Learn uses a few special variables that control some of
     its features.  This section will review each of these in
     detail.  These are located at the top of JB-LEARN.MAC.  Here
     is the list of variables and their definitions:

     AUTORESP  This variable controls whether or not the user
               should be asked to confirm responses found in the
               data file or not.  If this is set to 'N', the user
               will have to confirm each match.  This is how you
               will achieve best results.  If you are daring set
               this to 'Y' and the learn will assume what it
               finds is correct.  You may or may not get a macro
               that works with AUTORESP set to 'Y'.  This is set
               to 'N' as the default.

     CAPTFILE  Jb-Learn uses a capture file to parse the BBS
               prompt.  This variable defines the name of this
               capture file.  The default name is
               COMMO_HOME\{JBLRN}.CAP.  This file is accessed a
               lot.  If you have a ram disk, re-assign this
               variable to a filename that would be placed in
               your ram disk.  This will speed up JB-Learn a great deal.

     DATAFILE  This variable contains the name of the learn
               target/response data file.  The default is
               LEARN.DAT.

     FON_FILE  This defines the name of the backup dialing directory FON file.
               This is used when adding a new entry to your personal dialing
               directory.  The default value for this variable is
               COMMO_HOME\{JBLRN}.FON.

     NOV_MENU  This variable defines whether a full-screen menu should be
               shown, or just an expert one line menu. Set to Y if you want
               novice menus.  Any other value assumes expert menu.

     SLKLIMIT  This variable sets the number of SSLOOK strings that can be
               defined.  The default is 15 ({COMMO}'s upper limit).  Set this
               to 0 to not allow SSLOOK strings to be defined.

     SSLKAUTO  Set this variable to Y if you want SSLOOKS to be automatically
               generated instead of LOOKFOR/SEND pairs.  This is only going to
               happen in the area that the data file is processed.  It will
               not affect the JB-Learn menu.

     WAITTIME  This variable defines the length of time after all
               modem activity stops before the learn process
               starts interacting with the user.  The default is
               10 seconds.  Change the definition if you would
               like.  Be careful though to keep it long enough.
               Making it too short will have disastrous affects
               in the learn engine.  If this variable is set as
               NULL, then this auto learn type feature is turned off.

Running Jb-Learn

     Once the link has been added to your dialing directory, just
     open the dialing directory with ALT-D and dial away.  The
     learn will start once you have connected.

     The following paragraphs will describe what activities will
     take place during the learn run.  Study this carefully.

JB-Learn Flow (What Actually Happens)?

     After you connect, you will see the following message on the
     status line:

     <ESC> FOR LEARN MODE

     You can press <ESCAPE> at any time to invoke the learn
     processor.  Do NOT press <ESCAPE> until all output from the
     modem has stopped.  This is crucial.  The WAITTIME variable
     determines how long the macro will wait after modem activity
     is seen before invoking the learn processor.  If you do not
     press <ESCAPE> the macro will automatically invoke the
     processor after the number of seconds you have defined in
     WAITTIME.  This is why WAITTIME should be set to at least 5
     to 7 seconds.

     Once the learn processor is invoked it will search the
     capture file for the BBS prompt.  If it can not find one, it
     will prompt the user for it.  So, be very observant when you
     look at the screen.  Most of the time the macro will
     determine the prompt.  In very rare cases, it may not find
     it.  This happens mostly if you press <ESCAPE> while the
     modem is sending data to the terminal screen.  Remember to
     not press <ESCAPE> until ALL output has stopped.  Once the
     BBS prompt has been determined, processing will continue.

     If this is the first time through the processor, we will
     need to define the macro file and label name to write to.
     You will be prompted for this information.  I suggest that
     you do NOT write to COMMO.MAC or JB-LEARN.MAC.  Name the
     macro something unique.  This is completely up to you though.
     You will next define the label name used for the macro.  The label name
     will be defaulted to the system name dialed.  You will then be asked to
     edit it.  Once this is done a check for invalid characters in the label
     name is made and the label name will be limited to 8 characters.  The
     following characters are checked for since they are not allowed in a
     label name: , : / { }.

     Remember, this label is going to be used in the dialing directory so make
     it something meaningful.  The macro name will also be used.  Keep both
     names meaningful.

     You will be prompted to see if you would like to use auto
     learn mode.  This allows you to set the AUTORESP variable.
     If set to 'Y', no prompting to confirm targets/responses is
     done.  See documentation about AUTORESP defined earlier in this file.

     A match of the BBS prompt along with a response is attempted from the
     SSLOOK strings you may have defined during learn mode.  If one is made,
     an automatic response is sent and learn continues until the next prompt.
     This allows for automatic response to SSLOOKS without really using SSLOOK
     logic during learn operation.  The BBS prompt strings must match exactly.

     The learn processor will now begin looking through the data
     file.  It is looking for a match from the BBS prompt it knows
     about with the targets defined in the data file.  If it can
     not find one, then control passes to the special learn menu.
     This menu will be described later.  It looks for a match and
     stops at the first one it finds.  This is why placement of
     the targets/responses is very important.  If it finds one, it
     first checks to see if the response is a {COMMO} variable.
     If it is, it translates it.  You are then asked to confirm
     the response to the BBS prompt.  If you answer 'Y', the code
     will be written to the macro and the learn processor begins
     all over again.  It will wait for your key press or the
     timeout period before attempting to process the next BBS
     prompt.  If you answer 'N', you will be taken to the learn menu.

     The learn processor will continue this way until you are
     done.  We will now discuss the learn menu.  This menu provides
     a great deal of control not available in other areas of the
     learn engine.

The JB-Learn Menu

     Here is what the learn menu will look like:

     JB-LEARN RESPONSE TYPE MENU - VERSION 1.2
     BBS PROMPT:

     C - CONTINUE LEARNING

     E - SEND <ENTER>

     H - TREAT AS A SINGLE KEY HOT KEY (NO <CR>)

     I - INSERT COMMENT INTO MACRO

     L - TREAT AS A SSLOOK STRING: (SSLOOK COUNT# )

     P - TREAT AS A PASSWORD

     Q - QUIT JB-LEARN

     R - REVISE/EDIT BBS PROMPT

     S - ENTER STANDARD BBS RESPONSE (WITH <CR>)

     W - SET WAIT TIME:
     X - TOGGLE BETWEEN NOVICE AND EXPERT MENU
     ENTER CHOICE: C,E,H,I,L,N,P,Q,R,S,W,X:

     The following paragraphs describe each option in this menu
          in detail.

C - CONTINUE LEARNING
     This option simply continues to learn.  Use this if you
     accidentally came here by mistake.

E - SEND <ENTER>
     Use this option if you just need to respond to the BBS
     prompt with a <ENTER> key.

H - TREAT AS A SINGLE KEY HOT KEY (NO <CR>)
     Many systems use what are called hot keys.  These are menu
     choices that simply require a one character response (no
     <ENTER> required).  This option will provide a way of sending
     these hot keys.

I - INSERT COMMENT INTO MACRO
     This option allows you to write a line to the macro file.
     This could be a comment or even additional commands.  This
     option simply takes what you enter and writes it to the
     macro.  Be very careful with this one.

L - TREAT AS A SSLOOK STRING
     This menu option allows you to create SSLOOK strings and place them into
     your macros.  Consult the {COMMO} documentation on what a SSLOOK command
     will do.  Basically, the SSLOOK should be used when nagging prompts
     appear often during a login session.  The SSLOOK will send the
     string/response you tell it when it sees the target.  You may have up to
     15 SSLOOKS active at one time.  When the menu appears, it will show you
     the current number of active SSLOOKS.  Consult the {COMMO} documentation
     (macro.doc) for more information on this capability.

P - TREAT AS A PASSWORD
     This option will send your password to the host and write
     macro code to do it in your macro.  The routine will check to
     see if you defined a password in the dialing directory.  If
     you have, it simply uses it.  If you did not, you will be
     asked for the password.

Q - QUIT JB-LEARN
     This option terminates the learn processor.  When this
     happens, final code is written to the macro file.  You are
     also asked if you want to create a new dialing directory
     entry in your dialing directory file.  If you answer yes you
     will be prompted for the system name (a default is provided
     if known), and the phone number will be asked for.  The
     routine will place the new entry just after the one already
     defined in the dialing directory.  The string '(WITH LEARN)'
     is appended to the system name.  If no entry matching the
     system name is seen, the entry will be placed at the end of
     your dialing directory.  The linked macro will automatically
     be defined for you based upon the input entered earlier. A backup of
     your original dialing directory file is made prior to any modifications.
     The name of this dialing directory file is defined with the variable
     FON_FILE.  Once this is done, the variables are cleared out of memory and
     the JB-Learn processor will be terminated.

R - REVISE/EDIT BBS PROMPT
     This option allows you to edit the BBS prompt.

S - ENTER STANDARD BBS RESPONSE (WITH <CR>)
     This option allows you to enter a string to send to the BBS.
     This string will be terminated with a <ENTER> character.

W - SET WAIT TIME:
     This option allows you to update the WAITTIME variable
     described above.

X - TOGGLE BETWEEN NOVICE AND EXPERT MENU
     This menu option toggles between the novice menu and the expert menu.
     You will be presented with a 1 line menu showing the letters available
     when in expert mode.  When in novice mode, the entire menu will be shown.

The JB-Learn Data File Format

     One of JB-Learn's strongest features is its use of a special
     data file to process potential BBS prompts and have possible
     responses to them.  This is accomplished with the use of the
     LEARN.DAT data file.  This file has a special data format
     that the macro uses to parse through.  Here are the rules for
     this data file:

     1.   Any comments desired in the file should begin with a
          space character in column 1.  Any lines beginning with a
          space are ignored.

     2.   The file may be of any size.

     3.   The response / target lines should look like this:

RESPONSE,TARGET
RESPONSE|,TARGET
N|,MORE Y/N?
%_PAS|,PASSWORD:

     The response comes first and begins in column 1 of the line.
     {COMMO} variables may be used.  Precede them with a %
     character.  If the value of the variable used in the data
     file is blank, you will be asked to define it during the
     learn macro processor.  Other special {COMMO} characters may
     also be used in the response string.  A list of these is
     below:

     CHARACTER DESCRIPTION

     ^M or |   Carriage return
     ^J        Linefeed
     ^I        TAB
     ^L        Formfeed
     ^[        Escape
     ^G        Bell
     ^S        XOFF
     ^Q        XON
     ^Z        End of file

     The response string is separated from the target (BBS
     prompt) by a comma ',' character.  Look at the examples shown
     above.  These show {COMMO} variables being used, standard
     strings, and the use of special characters (like | to
          represent a <CR> character).

     The macro will append strings to the data file if you tell
     it to when asked.  These entries will follow the format
     described here.  This format is also used in the CS-LEARN
     macro product as well.  So, if you are using that one as
     well, the data file will work the same way.

The Future of JB-Learn

     Like any other product, I hope to continue to evolve
     JB-Learn.  Here are a few ideas that you will probably see in
     future versions of JB-Learn:

     -    A more automated setup routine to add the JB-Learn link
          to your dialing directory.  This will help the beginning
          users a great deal.

     -    I would like to expand the LEARN.DAT data file to
          contain more strings and responses.  This will help all of us.
          If you want to contribute, just send them my way.

     -    Add all user suggestions that are possible with {COMMO}'s rich
          programming language.  Start sending them my way.

     Again, this macro is another learning project for all of you
     to study.  If you make changes to it that are significant in
     nature, please send them my way.  My contact information is
     located at the end of this document.  Let us make this thing
     sing and dance even better!

Thanks

     I would like to thank the following people:

My Wife (Keri)
     My wonderful wife who puts up with a programmer that stays
     up all night.  She tells me she is my second love.  Well,
     hmmmmm ... Just kidding <GRIN>.

Fred Brucker
     I would like to thank Fred for the great product {COMMO}.  I
     would also like to thank him for the great SFI enhancements
     he has made to the program.  Without that, it would have
     never even been possible to use it.  Thank you very much
     Fred! Keep up the good work!

Chuck Seyboldt
     Thanks to Chuck for the wonderful suggestions regarding
     {COMMO} macro programming tricks and tips.  Good work sir and
     keep CS-MAC alive.  You are an inspiration to me.

Jim Bennett
     I would like to thank Jim for the technical review of JB
     Learn.  Without it some nasty little bugs would have been
     seen by all of you.  Thanks Jim.  Also, thanks to Jim for the
     use of his BBS to distribute JB-Learn (more on that later).

Contact Information

     I value all of your input.  Please contact me with any
     suggestions you may have.  You can contact me via the following methods:

     Jeff Bishop
     Mailing Address: 420 E Yavapai RD. NO. H Tucson, AZ 85705
     E-Mail Address : [e-mail] (my PGP public key in MYPUBLIC.KEY)
     Voice Phone    : [phone] (evenings before 12:00AM EST).

     I can also be reached in the COMMO conference in the fidonet and WME
     message networks.  Post a message to "jeff bishop" and I will surely
     respond to it.

Getting JB-Learn Updates

     JB-Learn is distributed in two different packages.  I am
     distributing it as a stand alone package and it is also in the
     CS-MAC package (version 13 and above).  If you are reading this from
     the CS-MAC archive, this may or may not be the latest one.  Use the
     information below to get the latest and greatest version.

     If you have access to the internet, you can use ftp to get JB Learn.
     Ftp to ftp.primenet.com.  Login as anonymous and send your e-mail
     address as the password.  Once logged in, cd to  /users/j/jbishop/commo.
     Once here, get the file jbl-*.zip.  This will get you the latest
     version. You are also welcome to get the latest version of CS-MAC
     here as well. Get the file cs*.zip.

     If you wish, you can also ftp to ftp.nlbbs.com. Login as anonymous and
     send your mail address as password. Once here, cd to /pub/cs-mac.

     If you do not have access to the internet, you can log in to the
     Demodulator BBS.  The phone number is 1-602-290-2807.  Use 'COMMO RELEASE'
     as your first and last name.  Use 'guest' as the password.  A menu will
     be presented to allow you to pick JB-Learn from.
     In addition, other {COMMO} products can be downloaded from this menu.